<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>insque</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_977">&nbsp;</a>NAME</h4><blockquote>
insque, remque - insert or remove an element in a queue
</blockquote><h4><a name = "tag_000_005_978">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="search.h.html">search.h</a>&gt;

void insque(void *<i>element</i>, void *<i>pred</i>);
void remque(void *<i>element</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_979">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>insque()</i>
and
<i><a href="remque.html">remque()</a></i>
functions manipulate queues built from doubly-linked lists.  The queue can be
either circular or linear.  An application using
<i>insque()</i>
or
<i><a href="remque.html">remque()</a></i>
must define a structure in which the first two members of the structure are
pointers to the same type of structure, and any further members are
application-specific.  The first member of the structure is a forward pointer
to the next entry in the queue.  The second member is a backward pointer to
the previous entry in the queue.  If the queue is linear, the queue is
terminated with null pointers.  The names of the structure and of the pointer
members are not subject to any special restriction.
<p>
The
<i>insque()</i>
function inserts the element pointed to by <i>element</i> into a
queue immediately after the element pointed to by <i>pred</i>.
<p>
The
<i><a href="remque.html">remque()</a></i>
function removes the element pointed to by <i>element</i> from a queue.
<p>
If the queue is to be used as a linear list, invoking
<i>insque</i>(&amp;<i>element</i>, NULL), where <i>element</i> is the initial
element of the queue, will initialise the forward and backward pointers of
<i>element</i> to null pointers.
<p>
If the queue is to be used as a circular list, the application must initialise
the forward pointer and the backward pointer of the initial element of the
queue to the element's own address.
</blockquote><h4><a name = "tag_000_005_980">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i>insque()</i>
and
<i><a href="remque.html">remque()</a></i>
functions do not return a value.
</blockquote><h4><a name = "tag_000_005_981">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_005_982">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_983">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The historical implementations of these functions described the
arguments as being of type <b>struct qelem *</b> rather than as being
of type <b>void *</b> as defined here.  In those implementations,
<b>struct qelem</b> was commonly defined in &lt;<b>search.h</b>&gt; as:
<pre>
<code>
struct qelem {
     struct qelem  *q_forw;
     struct qelem  *q_back;
};
</code>
</pre>
Applications using these functions, however, were never able to
use this structure directly since it provided no room for
the actual data contained in the elements.  Most applications
defined structures that contained the two pointers as the
initial elements and also provided space for, or pointers to,
the object's data.  Applications that used these functions to
update more than one type of table also had the problem of
specifying two or more different structures with the same
name, if they literally used <b>struct qelem</b> as specified.
<p>
As described here, the implementations were actually expecting
a structure type where the first two members were forward and
backward pointers to structures.  With C compilers that didn't
provide function prototypes, applications used structures as
specified in the DESCRIPTION above and the compiler did what
the application expected.
<p>
If this method had been carried forward with an ISO C compiler
and the historical function prototype, most applications would
have to be modified to cast pointers to the structures actually
used to be pointers to <b>struct qelem</b> to avoid compilation
warnings.  By specifying <b>void *</b> as the argument type,
applications won't need to change (unless they specifically
referenced <b>struct qelem</b> and depended on it being defined in
&lt;<b>search.h</b>&gt;).
</blockquote><h4><a name = "tag_000_005_984">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_985">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="search.h.html">&lt;search.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
